<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="lib.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python documentation Index' />
<link rel="first" href="lib.html" title='Python library Reference' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="doctest-simple-testfile.html" />
<link rel="prev" href="module-doctest.html" />
<link rel="parent" href="module-doctest.html" />
<link rel="next" href="doctest-simple-testfile.html" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name='aesop' content='information' />
<title>23.2.1 Simple Usage: Checking Examples in Docstrings</title>
</head>
<body>
<div class="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="23.2 doctest  "
  href="module-doctest.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></a></td>
<td class='online-navigation'><a rel="parent" title="23.2 doctest  "
  href="module-doctest.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up one Level' width='32' /></a></td>
<td class='online-navigation'><a rel="next" title="23.2.2 simple Usage: Checking"
  href="doctest-simple-testfile.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></a></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></a></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></a></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="module-doctest.html">23.2 doctest  </a>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-doctest.html">23.2 doctest  </a>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="doctest-simple-testfile.html">23.2.2 Simple Usage: Checking</a>
</div>
<hr /></div>
</div>
<!--End of Navigation Panel-->

<h2><a name="SECTION0025210000000000000000"></a><a name="doctest-simple-testmod"></a>
<br>
23.2.1 Simple Usage: Checking Examples in
            Docstrings
</h2>

<p>
The simplest way to start using doctest (but not necessarily the way
you'll continue to do it) is to end each module <tt class="module">M</tt> with:

<p>
<div class="verbatim"><pre>
def _test():
    import doctest
    doctest.testmod()

if __name__ == "__main__":
    _test()
</pre></div>

<p>
<tt class="module"><a href="module-doctest.html">doctest</a></tt> then examines docstrings in module <tt class="module">M</tt>.

<p>
Running the module as a script causes the examples in the docstrings
to get executed and verified:

<p>
<div class="verbatim"><pre>
python M.py
</pre></div>

<p>
This won't display anything unless an example fails, in which case the
failing example(s) and the cause(s) of the failure(s) are printed to stdout,
and the final line of output is
"<tt class="samp">***Test Failed*** <var>N</var> failures.</tt>", where <var>N</var> is the
number of examples that failed.

<p>
Run it with the <b class="programopt">-v</b> switch instead:

<p>
<div class="verbatim"><pre>
python M.py -v
</pre></div>

<p>
and a detailed report of all examples tried is printed to standard
output, along with assorted summaries at the end.

<p>
You can force verbose mode by passing <code>verbose=True</code> to
<tt class="function">testmod()</tt>, or
prohibit it by passing <code>verbose=False</code>.  In either of those cases,
<code>sys.argv</code> is not examined by <tt class="function">testmod()</tt> (so passing
<b class="programopt">-v</b> or not has no effect).

<p>
For more information on <tt class="function">testmod()</tt>, see
section&nbsp;<a href="doctest-basic-api.html#doctest-basic-api">23.2.4</a>.

<p>

<div class="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="23.2 doctest  "
  href="module-doctest.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></a></td>
<td class='online-navigation'><a rel="parent" title="23.2 doctest  "
  href="module-doctest.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up one Level' width='32' /></a></td>
<td class='online-navigation'><a rel="next" title="23.2.2 simple Usage: Checking"
  href="doctest-simple-testfile.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></a></td>
<td align="center" width="100%">Python Library Reference</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></a></td>
<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
  border='0' height='32'  alt='Module Index' width='32' /></a></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></a></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="module-doctest.html">23.2 doctest  </a>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="module-doctest.html">23.2 doctest  </a>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="doctest-simple-testfile.html">23.2.2 Simple Usage: Checking</a>
</div>
</div>
<hr />
<span class="release-info">Release 2.5.1, documentation updated on 18th April, 2007.</span>
</div>
<!--End of Navigation Panel-->
<address>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</address>
</body>
</html>
